Personal Computer World 2007 September/PCWSEP07.iso/Software/Full/NetObjects Fusion 9 Standard/NOF9_Full_EN.exe/data1.cab/FSI/lib/innovative/menu.js

JavaScript | 2005-11-16 | 19.5 KB | 819 lines

/****i* SOURCE_FILE/INFO
 *
 * NAME
 *  menu.js
 *
 * USAGE
 *  Part of IS JavaScript Library.
 *
 * COPYRIGHT
 *  Copyright ⌐ 1999-2000 Innovative Systems SRL.
 *  All Rights Reserved.
 *
 *  This is an unpublished work protected by Innovative Systems SRL
 *  as a trade secret, and is not to be used or disclosed except as
 *  expressly provided in a written license agreement executed by
 *  you and Innovative Systems SRL.
 *
 *      <[e-mail]>
 *
 * NOTES
 *  JavaScript code.
 *
 *****/

/****h* IS_JavaScript_Library/menu
 *
 * NAME
 *  IS JavaScript Library / menu module
 *
 * DESCRIPTION
 *  Menu related functionality.
 *
 ****/

var IS = IS_getLibHandle();


if (typeof (IS) != "undefined" && typeof (IS.Location) == "undefined")
{
/****c* ISJS/Location
 *
 * NAME
 *  ISJS::Location (id, target, href)
 *
 * USAGE
 *  id     -- Object identifier.
 *            Distinguishes the location within a locations collection.
 *            Should be unique among the collection.
 *  target -- Name of a frame within the browser.
 *  href   -- Uniform Resource Locator (the URL) to be loaded by the browser.
 *
 * DESCRIPTION
 *    By selecting a tree or menu item an ôactionö is usually performed. Within IS
 *  JavaScript library such an ôactionö is translated to one or more commands given to the
 *  browser to load a specified URL into a specified frame.
 *    ISJS::Location objects gather together these two pieces of information: a target
 *  browser frame (target property) and an URL (href property).
 *    Every item, both menu and tree, has associated a collection of locations retaining
 *  thus the actions attached to them.
 *
 * SEE ALSO
 *  Container, Menu, Tree.
 *
 ****/
function IS_Location (target, href)
{
  // __proto__ initialization
  this.__proto__ = IS_Location.prototype;

  // properties
  //this.id = id;
  this.target = target;
  this.href = href;
}

// add Location class to IS namespace
IS.__proto__.Location = IS_Location;
}

if (typeof (IS) != "undefined" && typeof(IS.Menu) == "undefined")
{


/****m* MenuItem/select
 *
 * NAME
 *  select ()
 *
 * DESCRIPTION
 *  Action when a menu item is selected.
 *  Separated into a method to make it overridable in sub-classes.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_Item_select ()
{
  var menu = this.owner;
  var document = menu.document;

  // clear previous selection
  var ignoreItemId = this.id;
  menu.clearSelection (ignoreItemId);

  // load associated locations
  var nLocationCount = this.locations.length;

  // first location (i = 0) already proceesed (see toHtml() method)
  for (var i = 1; i < nLocationCount; i++)
  {
    var location = this.locations[i];
    if (typeof (IS.incHidden) != "undefined" && IS.incHidden == true && location.target == IS.HiddenFrame.frame.name)
    {
      eval (location.href);
    }
    else
    {
      var target = IS.getFrameByName (location.target);
      if (null != target)
      {
        target.location.replace( location.href );
      }
      else
      {
        //alert( "Invalid frame name specified (" + location.target + ")!"
        //      + "\n Review Menu initialization." );
      }
    }
  }
}


/****m* MenuItem/setCompleted
 *
 * NAME
 *  setCompleted (isCompleted)
 *
 * USAGE
 *
 * DESCRIPTION
 *    Sets item status as completed. If the item status changed (from uncompleted to
 *  completed) statusChange() method is called.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_Item_setCompleted (isCompleted)
{
  isCompleted = (isCompleted == null ? true : isCompleted);
  if (this.isCompleted != isCompleted)
  {
    this.isCompleted = isCompleted;
  }
}

/****m* MenuItem/setSelected
 *
 * NAME
 *  setSelected (isSelected)
 *
 * USAGE
 *
 * DESCRIPTION
 *    Sets item status as selected. If the item status changed (from unselected to
 *  selected) statusChange() method is called.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_Item_setSelected (isSelected)
{
  isSelected = (isSelected == null ? true : isSelected);
  if (this.isSelected != isSelected)
  {
    this.isSelected = isSelected;
  }
}


/****m* MenuItem/setFocused
 *
 * NAME
 *  setFocused (isFocused)
 *
 * USAGE
 *
 * DESCRIPTION
 *    Sets item status as focused. If the item status changed (from unfocused to
 *  focused) statusChange() method is called.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_Item_setFocused (isFocused)
{
  isFocused = (isFocused == null ? true : isFocused);
  if (this.isFocused != isFocused)
  {
    this.isFocused = isFocused;
    if (typeof ("top") != "undefined" && typeof ("top.status") != "undefined")
    {
      top.status = (isFocused ? this.tip : "");
    }
  }
}


/****m* MenuItem/onMouseOver
 *
 * NAME
 *  onMouseOver()
 *
 * USAGE
 *
 * DESCRIPTION
 *  Called (by browser) when the mouse enters the image associated to the item.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_Item_onMouseOver()
{
  this.setFocused (true);
}


/****m* MenuItem/onMouseOut
 *
 * NAME
 *  onMouseOut()
 *
 * USAGE
 *
 * DESCRIPTION
 *  Called (by browser) when the mouse exits the image associated to the item.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_Item_onMouseOut()
{
  this.setFocused (false);
}


/****m* MenuItem/onClick
 *
 * NAME
 *  onClick()
 *
 * USAGE
 *
 * DESCRIPTION
 *  Called (by browser) when the mouse clicks the image associated to the item.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_Item_onClick()
{
  this.setSelected (true);
  this.select ();
}

/****m* MenuItem/toHTML
 *
 * NAME
 *  toHTML (menu)
 *  toHTML (target, href)
 *
 * USAGE
 *  menu -- Menu object to which this item belongs.
 *
 * DESCRIPTION
 *  Generates the HTML document portion corresponding to the item.
 *
 * RETURN VALUE
 *  none
 *
 ****/

function IS_Menu_Item_toHTMLItemF (self, target, href)
{
  var varName = self.owner.varName;
  return (
       "<A NAME=\"" + self.id + "\"" +
         (this.isSelected
              ? "HREF=\"javascript:void 0\""
              : "\" TARGET=\"" + target + "\" HREF=\"" + href + "\"") +
       "   onMouseOver=\"" + varName + ".getItem(\'" + self.id + "\').onMouseOver();\"" +
       "   onMouseOut=\"" + varName + ".getItem(\'" + self.id + "\').onMouseOut();\"" +
       "   onClick=\"" + varName + ".getItem(\'" + self.id + "\').onClick();\">" +
       self.label +
       "</A>" );
}

function IS_Menu_Item_toHTML (itemF)
{
    if (itemF == null)
        { itemF = IS_Menu_Item_toHTMLItemF; }

    var document = this.owner.document;
    var target = null;
    var href = null;

    if (this.locations.length > 0)
    {
        var firstLocation = this.locations[0];
        target = firstLocation.target;
        href = firstLocation.href;
    }

    document.writeln (itemF (this, target, href));
}


/****c* ISJS/MenuItem
 *
 * NAME
 *  ISJS::MenuItem( id, owner, tip, resCompleted, resUncompleted )
 *
 * USAGE
 *  id             -- Object identifier.
 *                    Distinguishes the item within the collection of the menu items
 *  owner          -- ISJS::Menu object to which this item belongs. Do not change this property
 *  tip            -- Tooltip associated to the item
 *  label          -- the label for this menu item
 *
 * DESCRIPTION
 *    A menu item has the following characteristics:
 *    - label;
 *    - status;
 *    - tip;
 *    - menu (to which it belongs);
 *    - associated action(s).
 *
 *    The item is presented to the user through its depiction, typically a label or an image.
 *
 *    The item status is a combination of three conditions:
 *    - completed / uncompleted;
 *    - selected / unselected;
 *    - focused / unfocused.
 *
 *    The item status depends on the mouse position to item image and user action:
 *    - when the user clicks the item image, the item goes into selected status. A menu can
 *  have at most one selected item at a time. Thus, an item selection causes the transition of
 *  every other item to the unselected status.
 *    - when the mouse enters the item, the item goes into focused status. When the
 *  mouse exits the item, the item goes into unfocused status;
 *    - the completed / uncompleted status is not directly accessed by the user; it is
 *  programmatically managed through the setCompleted() / clearCompleted() method pair.
 *
 *    Selecting an item will tell the browser to execute its associated actions; the actions
 *  are translated into URL calls (see IS.Location description for more details). The
 *  browser status will be set with the item tip.
 *
 *    A menu item belongs to a menu (the menu has, usually, a collection of items). To be
 *  identified in the item collection a menu item has to have a distinct identifier (id
 *  property.)
 *
 *    A menu item is capable (aided by the menu to which it belongs) to generate its HTML
 *  representation (toHtml() method.)
 *
 * NOTES
 *
 * SEE ALSO
 *  Menu, SelectableRes
 *
 ****/
function IS_MenuItem (id, label, tip, locations, owner)
{
  // __proto__ initialization
  this.__proto__ = IS_MenuItem.prototype;

  // properties
  this.id    = id;     // must be unique among the menu item collection
  this.label = label;  // menu label (text or image)
  this.tip   = tip;    // menu item's tooltip on the status bar
  this.owner = owner;  // menu item's owner (if any)

                         // locations loaded on selection
  this.locations = (
         (locations != null)
          ? ((typeof (locations.length) != "undefined") ? locations : new Array (locations))
              : (new Array (0)));

  // status flag(s)
  this.isCompleted = false; // none, one or many (possible all) item(s) on a menu may be completed at a time
  this.isSelected  = false; // none or one item on a menu may be selected at a time
  this.isFocused   = false; // none or one item on a menu may be focused at a time

    // methods
  // ...status related
  this.setCompleted = IS_Menu_Item_setCompleted;
  this.setSelected  = IS_Menu_Item_setSelected;
  this.setFocused   = IS_Menu_Item_setFocused;

  // ...action related
  this.select       = IS_Menu_Item_select;

  // ...event handler(s)
  this.onMouseOver  = IS_Menu_Item_onMouseOver;
  this.onMouseOut   = IS_Menu_Item_onMouseOut;
  this.onClick    = IS_Menu_Item_onClick;

  // ...HTML related
  this.toHTML = IS_Menu_Item_toHTML;   // HTML reflection of the menu item
}

// add MenuItem class to IS namespace
IS.__proto__.MenuItem = IS_MenuItem;




/****m* Menu/getItemCount
 *
 * NAME
 *  getItemCount()
 *
 * USAGE
 *
 * DESCRIPTION
 *  Finds out the total number of the items managed by the menu.
 *
 * RETURN VALUE
 *  Number of the menu items (objects) within the menu.
 *
 ****/
function IS_Menu_getItemCount()
{
  return this.items.length;
}


/****m* Menu/getItemPos
 *
 * NAME
 *  getItemPos( itemId )
 *
 * USAGE
 *  itemId -- the identifier of the item whose position is to be retrieved
 *
 * DESCRIPTION
 *  Retrieves the position of an item from the menu collection.
 *
 * RETURN VALUE
 *  [integer] -û the position of the element if successful (the menu collection contains an item
 *                with the specified identifier)
 *  -1        û- otherwise
 *
 ****/
function IS_Menu_getItemPos (itemId)
{
  var nItemCount = this.items.length;
  for (var i = 0; i < nItemCount; i++)
  {
    if (this.items[i].id == itemId)
    {
      return i;
    }
  }

  return -1;
}


/****m* Menu/getItem
 *
 * NAME
 *  getItem( itemId )
 *
 * USAGE
 *  itemId -- the identifier of the item to be retrieved
 *
 * DESCRIPTION
 *  Retrieves an item from the menu collection.
 *
 * RETURN VALUE
 *  [object] -û ISJS::MenuItem object, if successful (the menu collection contains an item
 *              with the specified identifier)
 *  null     û- in any other case
 *
 ****/
function IS_Menu_getItem (itemId)
{
  var pos = this.getItemPos (itemId);
  return (pos == -1 ? null : this.items[pos]);
}


/****m* Menu/setItem
 *
 * NAME
 *  setItem( itemId, newItem )
 *
 * USAGE
 *  itemId  -- the identifier of the item to be replaced
 *  newItem -- the new item which will replace the one with the identifier æitemIdÆ
 *
 * DESCRIPTION
 *  Replaces a menu item.
 *
 * RETURN VALUE
 *  true  -û if successful (the item was changed)
 *  false û- if failed.
 *
 * NOTES
 *  (*) The request to change an item with a non-existent id within the menu collection will
 *      fail.
 *
 ****/
function IS_Menu_setItem( itemId, newItem )
{
  newItem.owner = this;
  var item = this.getItem( itemId );
  if (item != null)
  {
    for ( var prop in item )
      if ( prop != "id" )
        eval( "item." + prop + " = newItem." + prop );

    return true;
  }

  return false;
}


/****m* Menu/addItem
 *
 * NAME
 *  addItem( newItem )
 *
 * USAGE
 *  newItem -- object to be added (of type ISJS::MenuItem)
 *
 * DESCRIPTION
 *  Adds a new item to the menu collection.
 *
 * RETURN VALUE
 *  true  -û if successful (the new item was added)
 *  false û- if failed
 *
 ****/
function IS_Menu_addItem (newItem)
{
  newItem.owner = this;
  this.items[this.items.length] = newItem; // this.items.push (newItem);
}


/****m* Menu/removeItem
 *
 * NAME
 *  removeItem( itemId )
 *
 * USAGE
 *  itemId -- the identifier of the item to be removed
 *
 * DESCRIPTION
 *  Removes an item from the menu collection.
 *
 * RETURN VALUE
 *  true  -û if successful (the item was removed)
 *  false û- if failed
 *
 * NOTES
 *  (*) The request to remove an item with a non-existent id within the menu collection will
 *      fail.
 *
 ****/
function IS_Menu_removeItem (itemId)
{
  var pos = this.getItemPos (itemId);
  if (pos != -1)
  {
    this.items.splice (pos, 1);
    return true;
  }
  else
  {
    return false;
  }

}


/****m* Menu/clearSelection
 *
 * NAME
 *  clearSelection (ignoreItemId)
 *
 * USAGE
 *  ignoreItemId -- the identifier of the menu item to be ignored
 *
 * DESCRIPTION
 *    Sets the items within the menu collection to unselected status, except for the
 *  specified item.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_clearSelection (ignoreItemId)
{
  for (var i = 0; i < this.items.length; i++)
  {
    var item = this.items[i];
    if (item.id != ignoreItemId)
    {
      item.setSelected (false);
    }
  }
}


/****m* Menu/setSelected
 *
 * NAME
 *  setSelected (itemId, isSelected)
 *
 * USAGE
 *
 * DESCRIPTION
 *    Sets item status as selected. The selection status of all other items is cleared.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_setSelected (itemId, isSelected)
{
  isSelected = (isSelected == null ? true : isSelected);
  var item = this.getItem (itemId);
  if (item != null)
  {
    if (isSelected)
    {
      this.clearSelection (itemId);
    }
    item.setSelected (isSelected);
    this.redraw ();
  }
}

/****m* Menu/toHtml
 *
 * NAME
 *  toHtml()
 *
 * USAGE
 *
 * DESCRIPTION
 *  Creates the HTML portion of the document corresponding to the menu.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_toHTMLHeaderF ()
{
  return (
    "<TABLE BORDER=\"0\" CELLPADDING=\"0\" CELLSPACING=\"0\">\n" +
    "  <TR>\n" +
    "    <TD>\n");
}

function IS_Menu_toHTMLFooterF ()
{
  return (
    "    </TD>\n" +
    "  </TR>\n" +
    "</TABLE>");
}

function IS_Menu_toHTML (headerF, itemF, footerF)
{
  var document = this.document;

  if (headerF == null)
     { headerF = (this.toHTMLHeaderF != null ? this.toHTMLHeaderF : IS_Menu_toHTMLHeaderF); }
  if (itemF == null)
     { itemF = (this.toHTMLItemF != null ? this.toHTMLItemF : null); }
  if (footerF == null)
     { footerF = (this.toHTMLFooterF != null ? this.toHTMLFooterF : IS_Menu_toHTMLFooterF); }

  document.write (headerF ());

  var items = this.items;
  for (var i = 0; i < items.length; i++)
  {
    var menuItem = items[i];
    if (menuItem.owner == null)
      { menuItem.owner = this; }

    menuItem.toHTML (itemF);

    if (this.direction == this.DIRECTION_VERTICAL)
      document.writeln ("<BR>");
  }

  document.write (footerF ());
}


/****m* Menu/redraw
 *
 * NAME
 *  redraw()
 *
 * USAGE
 *
 * DESCRIPTION
 *  Generates a menu redraw event.
 *
 * RETURN VALUE
 *  none
 *
 ****/
function IS_Menu_redraw ()
{
  if (this.document != null)
  {
    this.document.location.reload();
  }
}


/****c* ISJS/Menu
 *
 * NAME
 *  ISJS::Menu(id, varName, owner)
 *
 * USAGE
 *  id      -- Object identifier.
 *             Distinguishes the menu within a menu collection.
 *  varName -- Name of the JavaScript variable representing this menu (used within
 *             toHtml() method.)
 *  owner   -- This property is currently not used.
 *
 * DESCRIPTION
 *    A menu offers to the user a quick and easy navigation among many options (using menu
 *  items; see ISLib.MenuItem for details.) There are no direct relations between those
 *  multiple options; they all have the same importance. There are no submenus (like in common
 *  Windows applications.)
 *
 *    A menu is responsible to create its representation in HTML format (toHtml() method.)
 *  This requirement implies that the menu should have access to the object representing the
 *  HTML document to which it belongs (document property) and acknowledge the name of the
 *  variable under which it is instantiated (varName property.) Both properties (document and
 *  varName) might be modified during the life of a menu.
 *
 *    A menu has associated a unique identifier (id property), which allows the creation of
 *  menu collections (see ISLib.Container for details.) Within a collection the identifier of
 *  a menu should be unique.
 *
 * NOTES
 *  (*) It is possible that the menu variable to be created before the creation of the HTML
 *      document which will contain it; in this case the document property of the menu should
 *      be properly set up when the HTML document is created (if possible in the <HEAD> tag
 *      section.)
 *
 * SEE ALSO
 *  MenuItem
 *
 ****/
function IS_Menu (id, varName, toHTMLFs, owner)
{
  // __proto__ initialization
  this.__proto__ = IS_Menu.prototype;

  // properties
  this.id     = id;
  this.owner    = owner;
  this.varName  = varName;              // name of the variable which hold the menu (used to create the HMTL)
  this.document = null;               // browser document which includes the menu (late binding)
  this.items    = new Array(0);

  if (toHTMLFs != null && typeof(toHTMLFs.length) != "undefined" && toHTMLFs.length == 3)
  {
    this.toHTMLHeaderF = toHTMLFs[0];
    this.toHTMLItemF   = toHTMLFs[1];
    this.toHTMLFooterF = toHTMLFs[2];
  }

  // displayed direction (horizontal vs. vertical)
  this.DIRECTION_HORIZONTAL = 1;
  this.DIRECTION_VERTICAL   = 2;

  // by default, displayed in horizontal view
  this.direction  = this.DIRECTION_HORIZONTAL;

  // methods
  this.getItemCount = IS_Menu_getItemCount;
  this.getItemPos   = IS_Menu_getItemPos;
  this.getItem      = IS_Menu_getItem;
  this.setItem      = IS_Menu_setItem;
  this.addItem      = IS_Menu_addItem;
  this.removeItem   = IS_Menu_removeItem;

  this.clearSelection = IS_Menu_clearSelection;
  this.setSelected    = IS_Menu_setSelected;

  this.toHTML = IS_Menu_toHTML;
  this.redraw = IS_Menu_redraw;
}

// add Menu class to IS namespace
IS.__proto__.Menu = IS_Menu;
}